<!DOCTYPE html>
<!-- Generated by pkgdown: do not edit by hand --><html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"><title>Use EJScreen API to get stats on one or more circular buffers — ejscreenapi • EJAM</title><!-- favicons --><link rel="icon" type="image/png" sizes="16x16" href="../favicon-16x16.png"><link rel="icon" type="image/png" sizes="32x32" href="../favicon-32x32.png"><link rel="apple-touch-icon" type="image/png" sizes="180x180" href="../apple-touch-icon.png"><link rel="apple-touch-icon" type="image/png" sizes="120x120" href="../apple-touch-icon-120x120.png"><link rel="apple-touch-icon" type="image/png" sizes="76x76" href="../apple-touch-icon-76x76.png"><link rel="apple-touch-icon" type="image/png" sizes="60x60" href="../apple-touch-icon-60x60.png"><script src="../deps/jquery-3.6.0/jquery-3.6.0.min.js"></script><meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"><link href="../deps/bootstrap-5.3.1/bootstrap.min.css" rel="stylesheet"><script src="../deps/bootstrap-5.3.1/bootstrap.bundle.min.js"></script><link href="../deps/font-awesome-6.4.2/css/all.min.css" rel="stylesheet"><link href="../deps/font-awesome-6.4.2/css/v4-shims.min.css" rel="stylesheet"><script src="../deps/headroom-0.11.0/headroom.min.js"></script><script src="../deps/headroom-0.11.0/jQuery.headroom.min.js"></script><script src="../deps/bootstrap-toc-1.0.1/bootstrap-toc.min.js"></script><script src="../deps/clipboard.js-2.0.11/clipboard.min.js"></script><script src="../deps/search-1.0.0/autocomplete.jquery.min.js"></script><script src="../deps/search-1.0.0/fuse.min.js"></script><script src="../deps/search-1.0.0/mark.min.js"></script><!-- pkgdown --><script src="../pkgdown.js"></script><meta property="og:title" content="Use EJScreen API to get stats on one or more circular buffers — ejscreenapi"><meta name="description" content="Get a data.table of EJScreen report results for one or multiple circular buffers."><meta property="og:description" content="Get a data.table of EJScreen report results for one or multiple circular buffers."><meta property="og:image" content="https://usepa.github.io/EJAM/logo.svg"></head><body>
    <a href="#main" class="visually-hidden-focusable">Skip to contents</a>


    <nav class="navbar navbar-expand-lg fixed-top bg-light" data-bs-theme="light" aria-label="Site navigation"><div class="container">

    <a class="navbar-brand me-2" href="../index.html">EJAM</a>

    <small class="nav-text text-warning me-auto" data-bs-toggle="tooltip" data-bs-placement="bottom" title="Released version">2.32.0</small>


    <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation">
      <span class="navbar-toggler-icon"></span>
    </button>

    <div id="navbar" class="collapse navbar-collapse ms-3">
      <ul class="navbar-nav me-auto"><li class="active nav-item"><a class="nav-link" href="../reference/index.html">Reference</a></li>
<li class="nav-item dropdown">
  <button class="nav-link dropdown-toggle" type="button" id="dropdown-articles" data-bs-toggle="dropdown" aria-expanded="false" aria-haspopup="true">Articles</button>
  <ul class="dropdown-menu" aria-labelledby="dropdown-articles"><li><hr class="dropdown-divider"></li>
    <li><h6 class="dropdown-header" data-toc-skip>Overview for EJAM Users</h6></li>
    <li><a class="dropdown-item" href="../articles/0_whatis.html">What is EJAM</a></li>
    <li><a class="dropdown-item" href="../articles/0_webapp.html">Using EJAM</a></li>
    <li><hr class="dropdown-divider"></li>
    <li><h6 class="dropdown-header" data-toc-skip>For analysts using R</h6></li>
    <li><a class="dropdown-item" href="../articles/1_installing.html">Installing the EJAM R package</a></li>
    <li><a class="dropdown-item" href="../articles/2_quickstart.html">Quick Start Guide</a></li>
    <li><a class="dropdown-item" href="../articles/3_analyzing.html">Basics of Using EJAM for Analysis in RStudio</a></li>
    <li><a class="dropdown-item" href="../articles/4_advanced.html">Advanced Features</a></li>
  </ul></li>
<li class="nav-item"><a class="nav-link" href="../news/index.html">Changelog</a></li>
      </ul><ul class="navbar-nav"><li class="nav-item"><form class="form-inline" role="search">
 <input class="form-control" type="search" name="search-input" id="search-input" autocomplete="off" aria-label="Search site" placeholder="Search for" data-search-index="../search.json"></form></li>
<li class="nav-item"><a class="external-link nav-link" href="https://github.com/USEPA/EJAM/" aria-label="GitHub"><span class="fa fab fa-github fa-lg"></span></a></li>
      </ul></div>


  </div>
</nav><div class="container template-reference-topic">
<div class="row">
  <main id="main" class="col-md-9"><div class="page-header">
      <img src="../logo.svg" class="logo" alt=""><h1>Use EJScreen API to get stats on one or more circular buffers</h1>
      <small class="dont-index">Source: <a href="https://github.com/USEPA/EJAM/blob/HEAD/R/ejscreenapi.R" class="external-link"><code>R/ejscreenapi.R</code></a></small>
      <div class="d-none name"><code>ejscreenapi.Rd</code></div>
    </div>

    <div class="ref-description section level2">
    <p>Get a data.table of EJScreen report results for one or multiple circular buffers.</p>
    </div>

    <div class="section level2">
    <h2 id="ref-usage">Usage<a class="anchor" aria-label="anchor" href="#ref-usage"></a></h2>
    <div class="sourceCode"><pre class="sourceCode r"><code><span><span class="fu">ejscreenapi</span><span class="op">(</span></span>
<span>  <span class="va">lon</span>,</span>
<span>  <span class="va">lat</span>,</span>
<span>  radius <span class="op">=</span> <span class="fl">3</span>,</span>
<span>  unit <span class="op">=</span> <span class="st">"miles"</span>,</span>
<span>  wkid <span class="op">=</span> <span class="fl">4326</span>,</span>
<span>  fips <span class="op">=</span> <span class="cn">NULL</span>,</span>
<span>  shapefile <span class="op">=</span> <span class="cn">NULL</span>,</span>
<span>  namestr <span class="op">=</span> <span class="st">""</span>,</span>
<span>  report_every_n <span class="op">=</span> <span class="fl">1000</span>,</span>
<span>  save_when_report <span class="op">=</span> <span class="cn">FALSE</span>,</span>
<span>  format_report_or_json <span class="op">=</span> <span class="st">"pjson"</span>,</span>
<span>  on_server_so_dont_save_files <span class="op">=</span> <span class="cn">FALSE</span>,</span>
<span>  ipurl <span class="op">=</span> <span class="st">"ejscreen.epa.gov"</span>,</span>
<span>  updateProgress <span class="op">=</span> <span class="cn">NULL</span>,</span>
<span>  drop_redundant_indicators <span class="op">=</span> <span class="cn">TRUE</span>,</span>
<span>  nicenames <span class="op">=</span> <span class="cn">FALSE</span>,</span>
<span>  verbose <span class="op">=</span> <span class="cn">TRUE</span>,</span>
<span>  getstatefromplacename <span class="op">=</span> <span class="cn">TRUE</span></span>
<span><span class="op">)</span></span></code></pre></div>
    </div>

    <div class="section level2">
    <h2 id="arguments">Arguments<a class="anchor" aria-label="anchor" href="#arguments"></a></h2>


<dl><dt id="arg-lon">lon<a class="anchor" aria-label="anchor" href="#arg-lon"></a></dt>
<dd><p>Longitude numeric vector</p></dd>


<dt id="arg-lat">lat<a class="anchor" aria-label="anchor" href="#arg-lat"></a></dt>
<dd><p>Latitude numeric vector</p></dd>


<dt id="arg-radius">radius<a class="anchor" aria-label="anchor" href="#arg-radius"></a></dt>
<dd><p>radius of circular buffer (uses a default if none specified)</p></dd>


<dt id="arg-unit">unit<a class="anchor" aria-label="anchor" href="#arg-unit"></a></dt>
<dd><p>"miles" (default) or "kilometers"</p></dd>


<dt id="arg-wkid">wkid<a class="anchor" aria-label="anchor" href="#arg-wkid"></a></dt>
<dd><p>optional spatial reference code, if default is not what is needed</p></dd>


<dt id="arg-fips">fips<a class="anchor" aria-label="anchor" href="#arg-fips"></a></dt>
<dd><p>if used instead of lon,lat it should be a character FIPS code vector
(counties, tracts, or blockgroups)</p></dd>


<dt id="arg-shapefile">shapefile<a class="anchor" aria-label="anchor" href="#arg-shapefile"></a></dt>
<dd><p>not implemented</p></dd>


<dt id="arg-namestr">namestr<a class="anchor" aria-label="anchor" href="#arg-namestr"></a></dt>
<dd><p>optional text</p></dd>


<dt id="arg-report-every-n">report_every_n<a class="anchor" aria-label="anchor" href="#arg-report-every-n"></a></dt>
<dd><p>Should it report ETA snd possibly save interim file after every n points</p></dd>


<dt id="arg-save-when-report">save_when_report<a class="anchor" aria-label="anchor" href="#arg-save-when-report"></a></dt>
<dd><p>optional, write .rdata file to working directory
with results so far, after ever n points, to have most results even if it crashes</p></dd>


<dt id="arg-format-report-or-json">format_report_or_json<a class="anchor" aria-label="anchor" href="#arg-format-report-or-json"></a></dt>
<dd><p>default is pjson but could modify to allow it to be report to get just a pdf URL
but that also can be gotten via <code><a href="url_ejscreen_report.html">url_ejscreen_report()</a></code></p></dd>


<dt id="arg-on-server-so-dont-save-files">on_server_so_dont_save_files<a class="anchor" aria-label="anchor" href="#arg-on-server-so-dont-save-files"></a></dt>
<dd><p>FALSE by default, but TRUE prevents saving any progress or crash-related files</p></dd>


<dt id="arg-ipurl">ipurl<a class="anchor" aria-label="anchor" href="#arg-ipurl"></a></dt>
<dd><p>which URL or IP to try</p></dd>


<dt id="arg-updateprogress">updateProgress<a class="anchor" aria-label="anchor" href="#arg-updateprogress"></a></dt>
<dd><p>Used to create progress bar in Shiny app</p></dd>


<dt id="arg-drop-redundant-indicators">drop_redundant_indicators<a class="anchor" aria-label="anchor" href="#arg-drop-redundant-indicators"></a></dt>
<dd><p>Set to FALSE if you do not want to exclude from results the indicators that appear twice
just under 2 different names, like RAW_D_LIFEEXP and RAW_HI_LIFEEXPPCT which are identical.</p></dd>


<dt id="arg-nicenames">nicenames<a class="anchor" aria-label="anchor" href="#arg-nicenames"></a></dt>
<dd><p>Set it to TRUE if you want to have it rename headers as long friendly plain English not R variable names
but note downstream functions mostly expect rname format
that uses <code><a href="ejscreenapi1.html">ejscreenapi1()</a></code> and <code><a href="ejscreenRESTbroker.html">ejscreenRESTbroker()</a></code>  and <code><a href="ejscreenRESTbroker2table.html">ejscreenRESTbroker2table()</a></code></p></dd>


<dt id="arg-verbose">verbose<a class="anchor" aria-label="anchor" href="#arg-verbose"></a></dt>
<dd><p>whether to print to console / viewer / plot</p></dd>


<dt id="arg-getstatefromplacename">getstatefromplacename<a class="anchor" aria-label="anchor" href="#arg-getstatefromplacename"></a></dt>
<dd><p>set to FALSE if you need the exact output of API and
TRUE if you want to try to extract ST abbrev and statename from the placename field,
which is more likely to be correct than the stateAbbr and stateName fields in the API output.</p></dd>

</dl></div>
    <div class="section level2">
    <h2 id="details">Details<a class="anchor" aria-label="anchor" href="#details"></a></h2>
    <p>Specify a radius and vector of latitude longitude points,
and get for a buffer the population weighted mean value of each raw indicator
like percent low-income, and total population count, and percentiles for those
raw indicator scores, all from EJScreen, as in an EJScreen standard report.</p>
<p>The functions <code><a href="ejscreenapi_plus.html">ejscreenapi_plus()</a></code> and <code><a href="ejscreenit.html">ejscreenit()</a></code> are higher-level functions
that provide renamed variables in their outputs.
Column names returned by ejscreenapi() are those provided by the EJScreen API,
e.g., RAW_D_INCOME, not the renamed variables like pctlowinc etc. or Percent Low Income</p>
<p><code><a href="ejscreenRESTbroker.html">ejscreenRESTbroker()</a></code> is the lowest level function here for access to the API.</p>
<p><code><a href="ejscreenRESTbroker2table.html">ejscreenRESTbroker2table()</a></code> converts that to a table.</p>
<p><code>ejscreenRESTbroker2table(ejscreenRESTbroker())</code>
returns the same 1-row data.frame as ejscreenapi1()
except the latter drops the percent signs and makes those values numeric,
converting text like 45% to the number 45.</p>
<p>This also drops redundant columns where the same numbers had been returned from API
using the normal name and a synonym name, as with TOTALPOP and "totalPop"</p>
<p>To compare API variable names and renamed versions:</p>
<p></p><div class="sourceCode"><pre><code><span id="cb1-1"><a href="#cb1-1" tabindex="-1"></a>x <span class="ot">&lt;-</span> <span class="fu">ejscreenapi</span>(<span class="sc">-</span><span class="dv">100</span>, <span class="dv">40</span>, <span class="dv">1</span>)</span>
<span id="cb1-2"><a href="#cb1-2" tabindex="-1"></a><span class="fu">cbind</span>(<span class="fu">names</span>(x), <span class="fu">fixnames</span>(<span class="fu">names</span>(x)))</span></code></pre><p></p></div>
<p>Note this and related functions could be recoded using httr2 and some
best practices, as described here: <a href="https://httr.r-lib.org/articles/api-packages.html" class="external-link">https://httr.r-lib.org/articles/api-packages.html</a>.</p>
<p>This relies on <code><a href="ejscreenapi1.html">ejscreenapi1()</a></code> to request URL of pdf report on each site
via the API, and does some error checking, but like <code><a href="ejscreenapi1.html">ejscreenapi1()</a></code> it does a GET
request via API and then parses the JSON results from the GET request, cleans it up,
adds URLs as links, compiles it as a data.table,
enables a progress bar, etc.</p>
<p>Note that this API is fairly slow, so it is fine for 10 sites, but not large numbers.
It varies, but can run about 1k to 10k sites per hour,
for circular buffers of 1 or 3 mile radius.
It sometimes fails to obtain results,
which may be caused by unreliable results from the API
rather than the code requesting results via the API.</p>
<p>See  <a href="https://www.epa.gov/ejscreen/ejscreen-api" class="external-link">https://www.epa.gov/ejscreen/ejscreen-api</a></p>
    </div>
    <div class="section level2">
    <h2 id="see-also">See also<a class="anchor" aria-label="anchor" href="#see-also"></a></h2>
    <div class="dont-index"><p><code><a href="ejscreenit.html">ejscreenit()</a></code> <code><a href="ejscreenapi_plus.html">ejscreenapi_plus()</a></code> <code>ejscreenapi()</code></p></div>
    </div>

    <div class="section level2">
    <h2 id="ref-examples">Examples<a class="anchor" aria-label="anchor" href="#ref-examples"></a></h2>
    <div class="sourceCode"><pre class="sourceCode r"><code><span> </span>
<span> <span class="kw">if</span> <span class="op">(</span><span class="cn">FALSE</span><span class="op">)</span> <span class="op">{</span> <span class="co"># \dontrun{</span></span>
<span> <span class="co"># Specify size of buffer circle and pick random points as example data</span></span>
<span> <span class="va">myradius</span> <span class="op">&lt;-</span> <span class="fl">1</span></span>
<span> <span class="va">pts2</span> <span class="op">&lt;-</span> <span class="fu"><a href="https://rdrr.io/r/base/data.frame.html" class="external-link">data.frame</a></span><span class="op">(</span>lon <span class="op">=</span> <span class="fu"><a href="https://rdrr.io/r/base/c.html" class="external-link">c</a></span><span class="op">(</span><span class="op">-</span><span class="fl">111.9040233</span>, <span class="op">-</span><span class="fl">73.7917865</span><span class="op">)</span>, lat <span class="op">=</span> <span class="fu"><a href="https://rdrr.io/r/base/c.html" class="external-link">c</a></span><span class="op">(</span><span class="fl">33.5604162</span>, <span class="fl">41.0613821</span><span class="op">)</span><span class="op">)</span></span>
<span> <span class="va">pts5</span> <span class="op">&lt;-</span> <span class="va">testpoints_5</span></span>
<span> </span>
<span> <span class="va">out</span> <span class="op">&lt;-</span> <span class="fu">ejscreenapi</span><span class="op">(</span>lon <span class="op">=</span> <span class="va">pts2</span><span class="op">$</span><span class="va">lon</span>, lat <span class="op">=</span> <span class="va">pts2</span><span class="op">$</span><span class="va">lat</span>, radius <span class="op">=</span> <span class="va">myradius</span><span class="op">)</span></span>
<span> <span class="fu"><a href="https://rdrr.io/r/utils/head.html" class="external-link">head</a></span><span class="op">(</span><span class="fu"><a href="https://rdrr.io/r/base/t.html" class="external-link">t</a></span><span class="op">(</span><span class="va">out</span><span class="op">)</span><span class="op">)</span></span>
<span> <span class="va">outnice</span> <span class="op">&lt;-</span> <span class="fu">ejscreenapi</span><span class="op">(</span>lon <span class="op">=</span> <span class="va">pts2</span><span class="op">$</span><span class="va">lon</span>, lat <span class="op">=</span> <span class="va">pts2</span><span class="op">$</span><span class="va">lat</span>, radius <span class="op">=</span> <span class="va">myradius</span>, nicenames <span class="op">=</span> <span class="cn">TRUE</span><span class="op">)</span></span>
<span> <span class="fu"><a href="https://rdrr.io/r/utils/head.html" class="external-link">head</a></span><span class="op">(</span><span class="fu"><a href="https://rdrr.io/r/base/t.html" class="external-link">t</a></span><span class="op">(</span><span class="va">outnice</span><span class="op">)</span>, <span class="fl">24</span><span class="op">)</span></span>
<span> <span class="op">}</span> <span class="co"># }</span></span>
<span> </span></code></pre></div>
    </div>
  </main><aside class="col-md-3"><nav id="toc" aria-label="Table of contents"><h2>On this page</h2>
    </nav></aside></div>


    <footer><div class="pkgdown-footer-left">
  <p>US EPA 2024</p>
</div>

<div class="pkgdown-footer-right">
  <p>EJAM Version 2.32.0</p>
</div>

    </footer></div>





  </body></html>

